------------------------------------------------------------------------------- Z X 8 1 C O R A L B A S I C I N T E R P R E T E R version 7.0 copyright by Carlo Delhez, 1987 - 1992 English manual first started 27th of September 1992 manual version 0.04 as of 92-12-08 ------------------------------------------------------------------------------- ZX81 Coral Basic Interpreter was first marketed by Terminal Software, Baarle Nassau, Netherlands. The original Dutch manual is ISBN 90-6883-041-4, first printed November 1987. ------------------------------------------------------------------------------- INTRODUCTION CBI is an acronym for Coral Basic Interpreter. It combines the efficiency of a new and fast Pseudo Screen Editor with the ease of a powerful extension of the ZX81 BASIC. CBI provides you with a new Full Entry Editor which can be used in Line Mode or Pseudo-Screen Mode. All the disadvantages of the (rather slow) regular ZX81 editor have vanished, e.g. as a result of the Auto Repeat on all keys, yet all its useful features, such as Direct Syntax Check and Pull Down Edit, are still available! Moreover, the Full Entry Editor is completely space-insensitive, so any computer freak can easily use a ZX81 now without actually having to know which keys to press to obtain the various keywords. Additionally, the ZX81 BASIC has been extended with 43 new commands and many `old' commands have been revised for faster or better operation. The new possibilities include: (1) Several useful programming aids, such as automatic line numbering, deletion of large blocks of program lines by a single command, data protection against NEW, CLEAR and RUN, program renumbering, tracing and deceleration of program execution, etc. (2) The possibility to use Pascal- and C-like structures, making commands like GOTO and GOSUB completely superfluous: Procedures with two-way data transport (any number of strings or numerical variables may be used for data exchange), conditional loop structures (DO, LOOP, EXIT, WHILE, UNTIL), expanded IF statement that allows for conditional execution of a block of program lines and also offers an ELSE condition. And ofcourse, all these structures may be nested at will! (3) Efficient data manipulations by way of commands like DATA, READ and RESTORE; easy stack manipulations via POP, PUSH, DUP, CLR STACK. (4) Useful applications for machine code programmers such as DPOKE, DPEEK and CALL, and also the unique possibility to expand the ZX81 BASIC even further with your own machinecode routines which may read the required parameters directly from BASIC. (5) Faster and improved graphical capabilities. Even though CBI offers so many advanced features, the actual code is only some 5k in length and is stored above RAMtop (by default). CBI is suited to be used with all existing ZX81 BASIC and machine code programs. Programs written in CBI can also be used on a `normal' ZX81, provided that you don't use the new commands in your program. STARTING CBI By default, the code of CBI is stored above RAMtop. Before loading the program, you must reserve space for the code. Type the following commands to achieve this: POKE 16388,8 POKE 16389,107 NEW Now you can load the program: LOAD "CBI" After loading, press any key to clear the ZX81. CBI can now be activated by a call to address 27400: RAND USR 27400 If all goes well, the normal message 0/0 should appear (yet one line higher than usual) and just below it a black block: the cursor. CBI is now ready to be used. NOTE 1 : In some cases the ZX81 may switch from CBI to its `normal' operating system (i.e. the K-cursor reappears). This happens for example after the NEW command. In such cases, CBI can be restarted by typing the command RAND USR 27400 again. If this doesn't bring you back to the CBI cursor, type POKE 16393,0 first, and then try again. If this still doesn't work, reset the ZX81 and reload CBI. NOTE 2 : If you wish to restart CBI without leaving it, the command POKE 16393,0 must be typed. This will refresh all the system variables held by CBI. NOTE 3 : As CBI is quite an extensive and advanced piece of software, it may still contain bugs. If you have problems with CBI or discover bugs, please contact me at the address at the bottom of this document. THE NEW COMMANDS In the following section, all new commands offered by CBI are summed up alphabetically with required syntax, brief explanation of usage and - where needed - one or more examples. The required syntax is written down with special symbols. These are: - bln : boolean value (zero for false or non-zero for true); a boolean value is used by conditional commands like IF. example: X100 - data_list : a list containing any number of numerical expression and/or string expressions, with successive entries separated by commas (','). String expressions need to be preceeded by a period ('.') as well. example: 81,.("ZX"+STR$ 81),92,."CBI" - name : consists out of alphanumerical symbols; the first symbol must be a letter (not a number). example: PROFIT89NET - sw : switch word; can be ON or OFF. - swv : switch value; can be 1 (for ON) or 0 (for OFF). - var : name of a numerical variable that need not be declared yet. example: OLDX or: A(10,3) - $var : name of a string variable that need not be declared yet. example: R$ or: X$(3) - x y z : numerical expressions. example: 127 or: 3*R/(2*Q*B(1)+1) or: COS(PI*H/6) - [...|...] : represents a choice between two possible items. example: [ UNTIL | WHILE ] - {...} : optional part of the sytax; may - but need not - be omitted. - {x} : numerical expression or nothing; when no numerical expression is typed by the user, the value x=0 will be assumed. ------ AUTO x STEP y -------------------------------------------------------- Each time the cursor appears on the screen, a line number will be printed automatically. The line number starts with value x and is incremented in steps y. The auto-function ends when an empty line is entered (i.e. by pressing NewLine immediately after the line number) or when the line number exceeds 9999. AUTO also works with numerical INPUT statements (may be used to show a default value which may be altered by the user). Example: AUTO 50 STEP 10 generates 50,60,70,... AUTO 92 STEP 9999 generates 92 only ------ BREAK sw ------------------------------------------------------------- Enables the user to enable/disable the break key function. When the edit mode is entered (e.g. after an error message), break is automatically enabled again. When the break key is disabled, a program can also not be halted by typing STOP for an INPUT value. Example: 10 BREAK OFF 20 DO UNTIL INKEY$="S" 30 LOOP This program can only be stopped by pressing "S". Note that the break key always remains enabled during LOAD and SAVE. ------ CALL x --------------------------------------------------------------- Calls the machine code program at address x. CALL replaces RAND USR and similar commands. Example: CALL 2602 wipes the screen (ROM routine for CLS). ------ CHAR x --------------------------------------------------------------- Equivalent to PRINT CHR$ x; but takes care of automatic scrolling when the screen gets filled in CBI-mode and is suited for all characters (including the new CBI keywords). Example: 10 FOR K=0 TO 255 20 CHAR K 30 NEXT K prints the entire character set. ------ CLR STACK ------------------------------------------------------------ Clears the entire stack. CLR STACK should be used after having interrupted a subroutine or a procedure by Break and you don't want to resume its execution. This prevents unwanted `stack growth'. Example: 10 GOSUB 30 20 STOP 30 CLR STACK 40 RETURN You'll get error 7/40 because CLR STACK deleted the return line number. ------ CURSOR x ------------------------------------------------------------- Lets CHR$(x) act as a cursor in the CBI line editor. Use only single-position characters (no keywords) and also no control codes (like NewLine). Example: CURSOR 131 gives 'half' a cursor. ------ DATA data_list ------------------------------------------------------- Provides the data for a READ statement. It is necessary to issue a RESTORE command at least once in the program in order that the data-pointer has a proper value. Example: 10 RESTORE 20 READ N$ 30 READ NUMBER 40 PRINT N$;NUMBER 50 DATA ."ZX",81 ------ DEF PROC name -------------------------------------------------------- Starts the definition of a procedure named 'name'. This definition must be ended by an END PROC statement. The procedure may be called by the command name{:data_list} and in case the data_list is added, the data-pointer will be set to point to it, so that the parameters in the list may be read by READ commands. When a DEF PROC is encountered during execution of a program, its entire definition block will be skipped (i.e. not executed). Procedure definitions may be nested, but this is not advised. DEF PROC should not be used as a direct command. Example: 10 DEF PROC ENIGMA 20 READ X$ 30 FOR K=1 TO LEN X$ 40 LET X$=X$(2*K-1)+X$ 50 NEXT K 60 END PROC .X$( TO LEN X$/2) 65 70 ENIGMA:."DESREVER" 80 READ E$ 90 PRINT E$ ------ DELETE x TO y -------------------------------------------------------- Removes all the lines with number x through y from the program. Neither line x nor line y need actually exist. DELETE may only be used as a direct command. Example: DELETE 0 TO 9999 deletes entire program ------ DO { [UNTIL|WHILE] bln } --------------------------------------------- The DO command indicates the beginning of a (conditional) loop structure, which has to be ended by a matching LOOP command. The three possible structures are: DO ... LOOP : unconditional (infinite) loop DO UNTIL bln ... LOOP : repeat until bln=true (1) DO WHILE bln ... LOOP : repeat while bln=true (1) It is possible to leap out of each of these three structures by way of an EXIT command within the loop. The DO...LOOP structures may be nested at will. Example: 10 INPUT X 20 LET Y=X 30 DO UNTIL Y*Y=X 40 LET Y0=Y 50 LET Y=(Y+X/Y)/2 60 IF Y0=Y THEN EXIT 70 PRINT "SQR(";X;")=";Y 80 LOOP ------ DPEEK var,x ---------------------------------------------------------- Double peek (word value), equivalent to the more cumbersome command: LET var=PEEK x+256*PEEK (x+1) Example: DPEEK DF,16396 lets DF point to the display file ------ DPOKE x,y ------------------------------------------------------------ Double poke (word value), equivalent to the more cumbersome set of commands: POKE x,y-256*INT (y/256) POKE x+1,INT (y/256) Example: DPOKE 32734,DF+1 has the effect of HOME (also see example at DPEEK for definition of DF). A number that has been stored by DPOKE can be read by DPEEK and vice versa. ------ DRAW TO x,y ---------------------------------------------------------- Draws the best possible line from the last plot position to position (x,y). Note that a line drawn from (a,b) to (c,d) is not exactly the same as a line drawn from (c,d) to (a,b). For wiping a line drawn by DRAW, UNDRAW must be applied in the same direction. Example: PLOT 0,0 DRAW TO 63,43 draws a line across the screen ------ DUP var -------------------------------------------------------------- Copies the value of the top element of the stack into variable var. The stack itself remains unaltered. Example: 10 DEF PROC WHERE 20 DUP RT 30 PRINT "CALLED FROM ";RT 40 END PROC 80 WHERE ------ EDIT x --------------------------------------------------------------- Moves line x (or the first line with a number higher than x) into the editor. May only be used as a direct command. ------ ELSE ----------------------------------------------------------------- To be used in combination with WHEN - see there. ------ END PROC {data_list} ------------------------------------------------- Indicates the end of a procedure definition. When the procedure is executed and the data_list after the END PROC is present, the data pointer will be set to point to this data_list, so READ commands can be used to read the data. For an example of a procedure with two-way data exchange see DEF PROC. ------ END WHEN ------------------------------------------------------------- Indicates the end of a WHEN structure - see WHEN for more details. ------ ERR MSGS sw ---------------------------------------------------------- When ERRor MeSsaGeS are on, all error messages will be briefly explained in plain English. Unknown error messages will be commented as 'ERROR?'. Example: ERR MSGS ON enable error messages PLOT 100,100 ... B/0 INTEGER OUT OF RANGE ------ ERROR x -------------------------------------------------------------- When CHR$(x) is a printable, non-control, single-position character, an error message with this character will be forced. Note that ERROR 28 has no effect. Example: ERROR 63 ... Z/0 ------ EXIT ----------------------------------------------------------------- Has two different applications: (1) as direct command: quit CBI (not a very sensible decision!); (2) in a program: jumps out of the current LOOP structure. For an example of case (2), see the DO command. ------ HOME ----------------------------------------------------------------- A fast and economic alternative for PRINT AT 0,0; ------ INDENT --------------------------------------------------------------- Gives your program a proper, professionally looking lay-out. Use INDENT to improve the legibility and surveyability of your program; the structure of your program is much clearer after using this command. When INDENT comes across a structural error in your program, it will stop its task. Note that INDENT may only be used as a direct command and sometimes results in undefined (and unimportant) error messages. ------ LINE var,x ----------------------------------------------------------- Puts into variable var the address where Basic line x or the first line with a number larger than x starts. The actual command of that line is then located at address var+4 (e.g. PRINT). Example: LINE FIRST,0 always FIRST=16509, start of basic area ------ LOOP ----------------------------------------------------------------- Indicates the end of a DO...LOOP structure - see DO for an example. ------ NOSTALGIC sw --------------------------------------------------------- Switches between the two possible edit modes: (1) NOSTALGIC ON : N-mode (nostalgic mode) (2) NOSTALGIC OFF : CBI-mode (Coral Basic mode, screen editor) For a more detailed description of N-mode and CBI-mode, please refer to the section "Using the new Editor". ------ ON/OFF --------------------------------------------------------------- These two reserved CBI keywords can only be used in combination with other CBI commands, viz. those that need 'sw' as parameter. Example: NOSTALGIC ON BREAK OFF ------ POP var -------------------------------------------------------------- Takes the top element off the stack and stores its value in variable 'var'. Example: 1000 DEF PROC ALTER 1010 POP CRA 1020 POP LRA 1030 IF LRA>=1E4 THEN LET LRA=1E4 1040 PUSH LRA 1050 PUSH CRA 1060 END PROC This procedure needs to be called just before the end of another procedure as to make sure that the latter does not cause error B when it was called by way of a direct command. ------ PROTECT sw ----------------------------------------------------------- Can be used to disable the commands CLEAR, RUN and NEW in order to protect programs and variables against against accidental loss. Example: PROTECT ON LET AMOUNT=99.95 CLEAR ------ PUSH x --------------------------------------------------------------- Stores the number x on top of the stack - see example at POP. ------ READ [var|$var] ------------------------------------------------------ The READ command is an important tool for data exchange between various parts of a program. The three different ways in which the READ command can be used are summed up below. In general, READ takes a data item from the data list that is specified by the current value of the data pointer. In case no data item can be found, error G results. (1) Combined with DATA and RESTORE; This is the most obvious usage - see DATA for an example. (2) Combined with PROCedures; Both while calling a procedure and while returning from it, data can be passed - see DEF PROC and END PROC. (3) By way of direct reading and/or setting of the data pointer (address 32732). The following program is an example of this method: 10 RAND PI 20 RESTORE 30 DATA 0 40 DPOKE 32732,16514 50 READ X 60 PRINT X ------ RESEQ x:y,z ---------------------------------------------------------- Resequences the program from line x onwards by renumbering this one to line y and proceeding with steps z. The RESEQ command does not change linenumbers after GOTO and GOSUB statements; taking into account the numerous possibilities for structured programming offered by CBI, this seems no restriction. Example: RESEQ 0:100,10 renumbers program as 100,110,120,... ------ RESTORE {x} ---------------------------------------------------------- Positions the data pointer on the first data element found in or after line x. Note that RESTORE without number looks for the first data element in the program. See DATA for an example. ------ TRACE swv;{x} -------------------------------------------------------- In case swv=1 a program will be traced during running: before executing subsequent lines of Basic, the line number will be displayed in the top righthand corner and a small pause (in length proportional to x) will be held. On a normal ZX81, use x=2750 for 1 second. Example: TRACE 1;2000 waits approx. 0.72 second ------ UNDRAW TO x,y -------------------------------------------------------- Works just like DRAW, but uses UNPLOT instead of PLOT. ------ UNTIL/WHILE ---------------------------------------------------------- These reserved CBI keywords can only be used in combination with a DO...LOOP structure. See DO for an example. ------ USER x --------------------------------------------------------------- Probably the most interesting command for machine code programmers. The USER command has the effect that subsequent '*' commands are redirected to the user-definable machine code routine at address x. This allows the user to easily expand the Basic with self-written routines. For a more detailed explanation, please refer to the section "Brief Explanation of the USER Command" ------ WHEN bln DO ---------------------------------------------------------- This command is an extension of the IF command and allows for conditional execution of program blocks (instead of just a single command). The stucture of a WHEN block within a program is as follows: WHEN bln DO ) > program lines to be executed when bln=true ) ELSE ) > program lines to be executed when bln=false ) END WHEN The ELSE with subsequent program lines is optional. WHEN...END WHEN structures may be nested at will. Example: 100 INPUT L$ 110 LET V$="AEIOU*" 120 FOR N=1 TO 6 130 WHEN L$=V$(N) AND T<6 DO 140 PRINT L$;" IS A VOWEL" 150 LET N=6 160 ELSE 170 WHEN N=6 DO 180 PRINT L$;" IS A CONSONANT" 190 END WHEN 200 END WHEN Also note that the '*' command (see USER) cannot be used after the THEN in an IF statement. Apply a WHEN construction instead. ------------------------------------------------------------------------------- For all questions or suggestions regarding CBI, please write to Carlo Delhez, Emmastraat 3, 4651 BV Steenbergen, Netherlands. Internet: tnndcarlo@cycl.phys.tue.nl (until May 1994) ------------------------------------------------------------------------------- <*** End of File ***>